home *** CD-ROM | disk | FTP | other *** search
/ Aminet 48 / Aminet 48 (2002)(GTI - Schatztruhe)[!][Apr 2002].iso / Aminet / text / edit / vim60rt.lha / Vim / vim60 / doc / if_ole.txt < prev    next >
Encoding:
Text File  |  2001-09-26  |  5.4 KB  |  155 lines
  1. *if_ole.txt*    For Vim version 6.0.  Last change: 2001 Sep 03
  2.  
  3.  
  4.           VIM REFERENCE MANUAL    by Paul Moore
  5.  
  6.  
  7. The OLE Interface to Vim                *ole-interface*
  8.  
  9. 1. Activation            |ole-activation|
  10. 2. Methods            |ole-methods|
  11. 3. The "normal" command        |ole-normal|
  12. 4. Registration            |ole-registration|
  13. 5. MS Visual Studio integration    |MSVisualStudio|
  14.  
  15. {Vi does not have any of these commands}
  16.  
  17. OLE is only available when compiled with the |+ole| feature.  See
  18. src/if_ole.INSTALL.
  19. An alternative is using the client-server communication |clientserver|.
  20.  
  21. ==============================================================================
  22. 1. Activation                        *ole-activation*
  23.  
  24. Vim acts as an OLE automation server, accessible from any automation client,
  25. for example, Visual Basic, Python, or Perl. The Vim application "name" (its
  26. "ProgID", in OLE terminology) is "Vim.Application".
  27.  
  28. Hence, in order to start a Vim instance (or connect to an already running
  29. instance), code similar to the following should be used:
  30.  
  31. [Visual Basic] >
  32.     Dim Vim As Object
  33.     Set Vim = CreateObject("Vim.Application")
  34.  
  35. [Python] >
  36.     from win32com.client.dynamic import Dispatch
  37.     vim = Dispatch('Vim.Application')
  38.  
  39. [Perl] >
  40.     use Win32::OLE;
  41.     $vim = new Win32::OLE 'Vim.Application';
  42.  
  43. Vim does not support acting as a "hidden" OLE server, like some other OLE
  44. Automation servers. When a client starts up an instance of Vim, that instance
  45. is immediately visible. Simply closing the OLE connection to the Vim instance
  46. is not enough to shut down the Vim instance - it is necessary to explicitly
  47. execute a quit command (for example, :qa!, :wqa).
  48.  
  49. ==============================================================================
  50. 2. Methods                        *ole-methods*
  51.  
  52. Vim exposes four methods for use by clients.
  53.  
  54.                             *ole-sendkeys*
  55. SendKeys(keys)        Execute a series of keys.
  56.  
  57. This method takes a single parameter, which is a string of keystrokes. These
  58. keystrokes are executed exactly as if they had been types in at the keyboard.
  59. Special keys can be given using their <..> names, as for the right hand side
  60. of a mapping. Note: Execution of the Ex "normal" command is not supported -
  61. see below |ole-normal|.
  62.  
  63. Examples (Visual Basic syntax) >
  64.     Vim.SendKeys "ihello<Esc>"
  65.     Vim.SendKeys "ma1GV4jy`a"
  66.  
  67. These examples assume that Vim starts in Normal mode. To force Normal mode,
  68. start the key sequence with CTRL-\ CTRL-N as in >
  69.  
  70.     Vim.SendKeys "<C-\><C-N>ihello<Esc>"
  71.  
  72. CTRL-\ CTRL-N returns Vim to Normal mode, when in Insert or Command-line mode.
  73. Note that this doesn't work halfway a Vim command
  74.  
  75.                             *ole-eval*
  76. Eval(expr)        Evaluate an expression.
  77.  
  78. This method takes a single parameter, which is an expression in Vim's normal
  79. format (see |expression|).  It returns a string, which is the result of
  80. evaluating the expression.
  81.  
  82. Examples (Visual Basic syntax) >
  83.     Line20 = Vim.Eval("getline(20)")
  84.     Twelve = Vim.Eval("6 + 6")        ' Note this is a STRING
  85.     Font = Vim.Eval("&guifont")
  86. <
  87.                             *ole-setforeground*
  88. SetForeground()        Make the Vim window come to the foreground
  89.  
  90. This method takes no arguments.  No value is returned.
  91.  
  92. Example (Visual Basic syntax) >
  93.     Vim.SetForeground
  94. <
  95.  
  96.                             *ole-gethwnd*
  97. GetHwnd()        Return the handle of the Vim window.
  98.  
  99. This method takes no arguments.  It returns the hwnd of the main Vimwindow.
  100. You can use this if you are writing something which needs to manipulate the
  101. Vim window, or to track it in the z-order, etc.
  102.  
  103. Example (Visual Basic syntax) >
  104.     Vim_Hwnd = Vim.GetHwnd
  105. <
  106.  
  107. ==============================================================================
  108. 3. The "normal" command                    *ole-normal*
  109.  
  110. Due to the way Vim processes OLE Automation commands, combined with the method
  111. of implementation of the ex command :normal, it is not possible to execute the
  112. :normal command via OLE automation. Any attempt to do so will fail, probably
  113. harmlessly, although possibly in unpredictable ways.
  114.  
  115. There is currently no practical way to trap this situation, and users must
  116. simply be aware of the limitation.
  117. ==============================================================================
  118. 4. Registration                    *ole-registration* *E243*
  119.  
  120. Before Vim will act as an OLE server, it must be registered in the system
  121. registry. In order to do this, Vim should be run with a single parameter of
  122. "-register".
  123.                             *-register*  >
  124.     gvim -register
  125.  
  126. Once vim is registered, the application path is stored in the registry. Before
  127. moving, deleting, or upgrading Vim, the registry entries should be removed
  128. using the "-unregister" switch.
  129.                             *-unregister*  >
  130.     gvim -unregister
  131.  
  132. The OLE mechanism will use the first registered Vim it finds.  If a Vim is
  133. already running, this one will be used.  If you want to have (several) Vim
  134. sessions open that should not react to OLE commands, use the non-OLE version,
  135. and put it in a different directory.  The OLE version should then be put in a
  136. directory that is not in your normal path, so that typing "gvim" will start
  137. the non-OLE version.
  138.  
  139.                             *-silent*
  140. To avoid the message box that pops up to report the result, prepend "-silent":
  141. >
  142.     gvim -silent -register
  143.     gvim -silent -unregister
  144.  
  145. ==============================================================================
  146. 5. MS Visual Studio integration            *MSVisualStudio* *VisVim*
  147.  
  148. The OLE version can be used to run Vim as the editor in Microsoft Visual
  149. Studio.  This is called "VisVim".  It is included in the archive that contains
  150. the OLE version.  The documentation can be found in the VisVim directory, the
  151. README.txt file.
  152.  
  153. ==============================================================================
  154.  vim:tw=78:ts=8:ft=help:norl:
  155.